Functions for Displaying File Previews2

The following section describes four functions that let you display file previews.

The Movie Toolbox provides two functions that allow you to display file previews in an Open dialog box in System 6 using standard file reply structures: SFGetFilePreview and SFPGetFilePreview . The Movie Toolbox also supplies two new functions that allow you to display file previews in an Open dialog box in System 7 using standard file reply structures: StandardGetFilePreview and CustomGetFilePreview .

All of these functions take the same parameters as their existing counterparts with the addition of a where parameter that allows you to specify the location of the upper-left corner of the dialog box. See Inside Macintosh: Files for information on the SFGetFile , SFPGetFile , StandardGetFile , and CustomGetFile routines.

The SFGetFilePreview , SFPGetFilePreview , StandardGetFilePreview , and CustomGetFilePreview functions allow the user to automatically convert files to movies if your application requests movies. If there is a file that can be converted into a movie file using a movie import component, then the file is shown in the Standard File dialog box in addition to any movies. When the user selects the file, the Open button changes to a Convert button. Figure 38 provides an example of this dialog box.

Choosing Convert displays a dialog box that allows the user to choose where the converted file should be saved. Figure 39 shows this dialog box.

When conversion is complete, the converted file is returned to the calling application as the movie that the user chose. If you want to disable automatic file conversion in your application, you must write a file filter function and pass it to the file preview display function you are using. Your file filter function must call the File Manager's FSpGetFileInfo function on each file that is passed to it to determine its actual file type. If the File System parameter block pointer passed to your file filter function indicates that the file type is 'MooV' , and the actual type returned by FSpGetFileInfo is not 'MooV' , then the file filter function will convert this file. If you do not wish a file to be displayed as a candidate for conversion, your file filter function should return a value of true when it is called for that file.

See "File Filter Functions," for comprehensive details on the interaction of application-defined file filter functions with the file preview display functions. For information of FSpGetFileInfo , see Inside Macintosh: Files.

Note
The functions described in this section do not appear in the MPW interface file Movies.h ; rather, they are listed in ImageCompression.h .

SFGetFilePreview

The SFGetFilePreview function allows you to display file previews in an Open dialog box using a standard file reply structure. This is the preferred function for displaying a file preview and it works with either System 7 or System 6.



 
pascal void SFGetFilePreview (Point where, 

                                         ConstStr255Param prompt,

                                         FileFilterUPP fileFilter,

                                         short numTypes,

                                         ConstSFTypeListPtr typeList,

                                         DlgHookUPP dlgHook, 

                                         SFReply *reply);

where: Specifies the location of the upper-left corner of the dialog box in global coordinates. If you set this point to (-1, -1), the Movie Toolbox centers the dialog box on the main screen. If you set this point to (-2, -2), the Movie Toolbox centers the dialog box on the screen that has the best display characteristics.
prompt: This parameter is ignored; it is included for historical reasons only.
fileFilter: Points to a function that filters the files that are displayed to the user in the dialog box. This is an optional function provided by your application; if you do not want to supply a filter function, set this parameter to nil . The SFGetFilePreview function uses this parameter along with the numTypes and typeList parameters to determine which files appear in the dialog box.; If this parameter is not nil , SFGetFilePreview calls the function for each file to determine whether to display the file to the user. The SFGetFilePreview function supplies you with the information it receives from the File Manager's GetFileInfo routine (see Inside Macintosh: Files for more information). Your function returns a Boolean value indicating whether to display the file. Set the Boolean value to false to cause the file to be displayed.; Your function must provide the following interface:



 
                    pascal Boolean MyFileFilter (ParmBlkPtr parmBlock);

See "File Filter Functions" for details.
numTypes: Specifies the number of file types in the array specified by the typeList parameter (a number between 1 and 4). Set this parameter to -1 to display all files.
typeList: Specifies an array of file types to be displayed to the user. The SFGetFilePreview function only displays files whose type matches an entry in this array (unless you set the numTypes parameter to -1; in this case, the function displays all files to the user). The ConstSFTypeListPtr data type is defined as follows:



 
                    typedef OSType ConstSFTypeListPtr[4];

dlgHook: Specifies a pointer to a custom dialog function. You can use this parameter to support a custom dialog box function you have supplied. If you are not supplying a custom dialog box function, set this parameter to nil . Your custom dialog function must present the following interface:



 
                    pascal short MyDlgHook (short item, 

                                         DialogPtr theDialog, 

                                         Ptr myDataPtr);

For more information about using custom dialog box functions with the SFGetFilePreview function, see "Custom Dialog Functions" .
reply: Contains a pointer to a standard file reply structure that is to receive information about the user's selection. See Inside Macintosh: Files for more information about reply structures.

DESCRIPTION

The SFGetFilePreview function presents an Open dialog box to the user and allows the user to view file previews during the dialog. This function corresponds to the File Manager's SFGetFile routine. See Inside Macintosh: Files for a complete description of the SFGetFile routine.

The SFGetFilePreview function takes the same parameters as its existing counterpart with the addition of a where parameter that allows you to specify the location of the dialog box.

The SFGetFilePreview function automatically converts files to movies if your application requests movies. If a file could be converted into a movie file using a movie import component, then the file is shown in the Standard File dialog box. See Figure 38 for the dialog box with an automatic file-to-movie conversion option and Figure 39 for the dialog box for saving a movie converted from a file.

Note
The SFGetFilePreview function does not appear in the MPW interface file Movies.h ; rather, it's listed in ImageCompression.h .

SFPGetFilePreview

The SFPGetFilePreview function allows you to display file previews in an Open dialog box using a standard file reply structure. This function differs from SFGetFilePreview in that you can provide a custom dialog box with any resource type and you can specify a modal-dialog filter function that allows you to gain greater control over the user interface.



 
pascal void SFPGetFilePreview (Point where, 

                                          ConstStr255Param prompt,

                                          FileFilterUPP fileFilter,

                                          short numTypes, 

                                          ConstSFTypeListPtr typeList,

                                          DlgHookUPP dlgHook, 

                                          SFReply *reply, short dlgID,

                                          ModalFilterUPP filterProc);

where: Specifies the location of the upper-left corner of the dialog box in global coordinates. If you set this point to (-1, -1), the Movie Toolbox centers the dialog box on the main screen. If you set this point to (-2, -2), the Movie Toolbox centers the dialog box on the screen that has the best display characteristics.
prompt: This parameter is ignored; it is included for historical reasons only.
fileFilter: Points to a function that filters the files that are displayed to the user in the dialog box. This is an optional function provided by your application; if you do not want to supply a filter function, set this parameter to nil . The SFGetFilePreview function uses this parameter along with the numTypes and typeList parameters to determine which files appear in the dialog box.; If this parameter is not nil , SFPGetFilePreview calls the function for each file to determine whether to display the file to the user. The SFPGetFilePreview function supplies you with the information it receives from the File Manager's GetFileInfo routine (see Inside Macintosh: Files for more information). Your function returns a Boolean value indicating whether to display the file. Set the Boolean value to false to cause the file to be displayed. See "File Filter Functions," which begins on File Filter Functions , for details on file filter functions.; Your function must provide the following interface:



 
                    pascal Boolean MyFileFilter (ParmBlkPtr parmBlock);

numTypes: Specifies the number of file types in the array specified by the typeList parameter. Specify a number between 1 and 4. Set this parameter to -1 to display all files.
typeList: Specifies an array of file types to be displayed to the user. The SFGetFilePreview function only displays files whose type matches an entry in this array (unless you set the numTypes parameter to -1; in this case, the function displays all files to the user). The ConstSFTypeListPtr data type is defined as follows:



 
                    typedef OSType ConstSFTypeListPtr[4];

dlgHook: Points to a custom dialog box function. You can use this parameter to support a custom dialog box function you have supplied by specifying a dialog template resource in your resource file (the dialog template's resource type must be set to 'DLOG' ; you must also supply an item list in a 'DITL' resource). You specify the dialog template's resource ID with the dlgID parameter. If you are not supplying a custom dialog function in this manner, set this parameter to nil .; Your custom dialog box function must present the following interface:



 
                    pascal short MyDlgHook (short item, 

                                         DialogPtr theDialog, 

                                         Ptr myDataPtr);

See "Custom Dialog Functions" for more information on using custom dialog functions with the SFPGetFilePreview function.
reply: Contains a pointer to a standard file reply structure that is to receive information about the user's selection. See Inside Macintosh: Files for more information about reply structures.
dlgID: Specifies the resource ID of your custom dialog template. You can use this parameter to specify a custom dialog template resource that has a resource type that differs from the standard value. Set this parameter to 0 to use the standard template.
filterProc: Points to your modal-dialog filter function. This function gives you greater control over the interface presented to the user. Your modal-dialog filter function must present the following interface:



 
                    pascal Boolean MyModalFilter (DialogPtr theDialog,

                                         EventRecord* theEvent,

                                         short itemHit, 

                                         Ptr myDataPtr);

See "Modal-Dialog Filter Functions," for details.

DESCRIPTION

The SFPGetFilePreview function presents an Open dialog box to the user and allows the user to view file previews during the dialog. This function corresponds to the File Manager's SFPGetFile routine. The SFPGetFilePreview function takes the same parameters as its existing counterpart with the addition of a where parameter that allows you to specify the location of the dialog box. See Inside Macintosh: Files for a complete description of the SFPGetFile routine and for more information about the parameters to this function.

The SFPGetFilePreview function automatically converts files to movies if your application requests movies. If a file could be converted into a movie file using a movie import component, then the file is shown in the Standard File dialog box. See Figure 38 for the dialog box with an automatic file-to-movie conversion option and Figure 39 for the dialog box for saving a movie converted from a file.

Note
The SFPGetFilePreview function does not appear in the MPW interface file Movies.h ; rather, it's listed in ImageCompression.h .

StandardGetFilePreview

The SFPGetFilePreview function allows you to display file previews in an Open dialog box using a standard file reply structure.



 
pascal void StandardGetFilePreview (FileFilterUPP fileFilter, 

                                         short numTypes, 

                                         ConstSFTypeListPtr typeList,

                                         StandardFileReply *reply);

fileFilter: Points to a function that filters the files that are displayed to the user in the dialog box. This is an optional function provided by your application; if you do not want to supply a filter function, set this parameter to nil . The StandardGetFilePreview function uses this parameter along with the numTypes and typeList parameters to determine which files appear in the dialog box.; If this parameter is not nil , StandardGetFilePreview calls the function for each file to determine whether to display the file to the user. The StandardGetFilePreview function supplies you with information identifying the file (see Inside Macintosh: Files for more information about the format of this parameter data). Your function returns a Boolean value indicating whether to display the file. Set the Boolean value to false to cause the file to be displayed.; Your function must provide the following interface:



 
                    pascal Boolean MyFileFilter (ParmBlkPtr parmBlock);

numTypes: Specifies the number of file types in the array specified by the typeList parameter (a number between 1 and 4). Set this parameter to -1 to display all files.
typeList: Specifies an array of file types to be displayed to the user. The StandardGetFilePreview function only displays files whose type matches an entry in this array (unless you set the numTypes parameter to -1; in this case, the function displays all files to the user). The ConstSFTypeListPtr data type is defined as follows:



 
                    typedef OSType ConstSFTypeListPtr[4];

reply: Contains a pointer to a reply structure that is to receive information about the user's selection. See Inside Macintosh: Files for more information about reply structures.

DESCRIPTION

The StandardGetFilePreview function presents an Open dialog box to the user and allows the user to view file previews. This function corresponds to the File Manager's StandardGetFile routine. See Inside Macintosh: Files for a comprehensive description of that routine and for more information about the parameters to this function. The StandardGetFilePreview function takes the same parameters as its existing counterpart with the addition of a where parameter that allows you to specify the location of the dialog box.

The StandardGetFilePreview function automatically converts files to movies if your application requests movies. If a file could be converted into a movie file using a movie import component, then the file is shown in the Standard File dialog box. See Figure 38 for the dialog box with an automatic file-to-movie conversion option and Figure 39 for the dialog box for saving a movie converted from a file.

Note
The StandardGetFilePreview function does not appear in the MPW interface file Movies.h ; rather, it's listed in ImageCompression.h .

CustomGetFilePreview

The CustomGetFilePreview function presents an Open dialog box to the user and allows the user to view file previews. This function differs from StandardGetFilePreview in that you can provide a custom dialog template and functions to support your template.

Note
The CustomGetFilePreview function is available only in System 7.



 
pascal void CustomGetFilePreview (FileFilterYDUPP fileFilter, 

                                          short numTypes,

                                          ConstSFTypeListPtr typeList,

                                          StandardFileReply *reply,

                                          short dlgID, 

                                          Point where, 

                                          DlgHookYDUPP dlgHook,

                                          ModalFilterYDProcPtr filterProc,

                                          short *activeList, 

                                          ActivateYDProcPtr activateProc, 

                                          void *yourDataPtr);

fileFilter: Points to a function that filters the files that are displayed to the user in the dialog box. This is an optional function provided by your application; if you do not want to supply a filter function, set this parameter to nil . The CustomGetFilePreview function uses this parameter along with the numTypes and typeList parameters to determine which files appear in the dialog box.; If this parameter is not nil , CustomGetFilePreview calls the function for each file to determine whether to display the file to the user. The CustomGetFilePreview function supplies you with information identifying the file (see Inside Macintosh: Files for more information about the format of this parameter data). Your function returns a Boolean value indicating whether to display the file. Set the Boolean value to false to cause the file to be displayed.; Your function must provide the following interface:



 
                    pascal Boolean MyFileFilter (ParmBlkPtr parmBlock);

numTypes: Specifies the number of file types in the array specified by the typeList parameter (a number between 1 and 4). Set this parameter to -1 to display all files.
typeList: Specifies an array of file types to be displayed to the user. The CustomGetFilePreview function only displays files whose type matches an entry in this array (unless you set the numTypes parameter to -1; in this case, the function displays all files to the user). The ConstSFTypeListPtr data type is defined as follows:



 
                    typedef OSType ConstSFTypeListPtr[4];

reply: Contains a pointer to a reply structure that is to receive information about the user's selection. See Inside Macintosh: Files for more information about reply structures.
dlgID: Specifies the resource ID of your custom dialog template. You can use this parameter to specify a custom dialog template resource that has a resource type that differs from the standard value. Set this parameter to 0 to use the standard template.
where: Specifies the location of the upper-left corner of the dialog box in global coordinates. If you set this point to (-1, -1), the Movie Toolbox centers the dialog box on the main screen. If you set this point to (-2, -2), the Movie Toolbox centers the dialog box on the screen that has the best display characteristics.
dlgHook: Points to a custom dialog function. You can use this parameter to support a custom dialog box function you have supplied by specifying a dialog template resource in your resource file. You specify the dialog template's resource ID with the dlgID parameter. If you are not supplying a custom dialog function, set this parameter to nil . For more information about using custom dialog functions with the CustomGetFile routine, see Inside Macintosh: Files. For details on the parameters of the custom dialog box function, see "Custom Dialog Functions" .; Your dialog hook function must present the following interface:



 
                    pascal short MyDlgHook (short item, DialogPtr 

                                         theDialog, Ptr myDataPtr);

filterProc: Points to your modal-dialog filter function. This function gives you greater control over the interface presented to the user. See Inside Macintosh: Files for more information about using modal-dialog filter functions with CustomGetFile .; Your modal-dialog filter function must present the following interface.



 
                    pascal Boolean MyModalFilter (DialogPtr theDialog,

                                         EventRecord* theEvent,

                                          short itemHit, 

                                         Ptr myDataPtr);

For details on the application-defined modal-dialog filter, see "Modal-Dialog Filter Functions," .
activeList: Contains a pointer to a list of all items in the dialog box that can be activated--that is, made the target of keyboard input. The list is stored as an array of integers. The first integer must contain the number of items in the array (not including this count value). The remaining array entries must contain item numbers that specify valid targets of keyboard input, in the order in which the items are to be activated. Set this parameter to nil to direct all keyboard input to the displayed list of filenames.
activateProc: Points to your activation function, which controls the highlighting of any items whose shape is known only by your application. See Inside Macintosh: Files for more information about standard file activation functions.; Your function must present the following interface:



 
                    pascal void MyActivateProc (DialogPtr theDialog, 

                                          short itemNo, 

                                          Boolean activating, 

                                          Ptr myDataPtr);

yourDataPtr: Contains a pointer to optional data that is supplied by your application to your callback functions. When the CustomGetFilePreview function calls any of your callback functions, it places this data on the stack, making it available to your functions. Set this parameter to nil if you are not supplying any optional data.

DESCRIPTION

The CustomGetFilePreview function is available only if the value of the Gestalt selector gestaltStandardFileAttr is true . (See Inside Macintosh: Overview for more information about this selector.) This function corresponds to the File Manager's CustomGetFile routine. The CustomGetFilePreview function takes the same parameters as its existing counterpart with the addition of a where parameter that allows you to specify the location of the dialog box. See Inside Macintosh: Files for a complete description of the CustomGetFile routine and for more information about the parameters to this function.

The CustomGetFilePreview function automatically converts files to movies if your application requests movies. If a file could be converted into a movie file using a movie import component, then the file is shown in the Standard File dialog box. See Figure 38 for the dialog box with an automatic file-to-movie conversion option and Figure 39 for the dialog box for saving a movie converted from a file.

Note
The CustomGetFilePreview function does not appear in the MPW interface file Movies.h ; rather, it's listed in ImageCompression.h .